.TH std::basic_string::operator+= 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_string::operator+= \- std::basic_string::operator+=

.SH Synopsis
   basic_string& operator+=( const basic_string& str );     \fB(1)\fP (constexpr since C++20)
   basic_string& operator+=( CharT ch );                    \fB(2)\fP (constexpr since C++20)
   basic_string& operator+=( const CharT* s );              \fB(3)\fP (constexpr since C++20)
   basic_string& operator+=( std::initializer_list<CharT>   \fB(4)\fP \fI(since C++11)\fP
   ilist );                                                     (constexpr since C++20)
   template< class StringViewLike >                         \fB(5)\fP \fI(since C++17)\fP
   basic_string& operator+=( const StringViewLike& t );         (constexpr since C++20)

   Appends additional characters to the string.

   1) Appends string str.
   2) Appends character ch.
   3) Appends the null-terminated character string pointed to by s.
   4) Appends characters in the initializer list ilist.
   5) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT,
   Traits> sv = t;, then appends characters in the string view sv as if by append(sv).
   This overload participates in overload resolution only if
   std::is_convertible_v<const StringViewLike&,
                         std::basic_string_view<CharT, Traits>> is true and
   std::is_convertible_v<const StringViewLike&, const CharT*> is false.

.SH Parameters

   str   - string to append
   ch    - character value to append
   s     - pointer to a null-terminated character string to append
   ilist - std::initializer_list with the characters to append
   t     - object (convertible to std::basic_string_view) with the characters to append

.SH Return value

   *this

.SH Complexity

   There are no standard complexity guarantees, typical implementations behave similar
   to std::vector::insert().

.SH Exceptions

   If the operation would result in size() > max_size(), throws std::length_error.

   If an exception is thrown for any reason, this function has no effect (strong
   exception safety guarantee).

.SH Notes

   Overload \fB(2)\fP can accept any types that are implicitly convertible to CharT. For
   std::string, where CharT is char, the set of acceptable types includes all
   arithmetic types. This may have unintended effects.

.SH Example


// Run this code

 #include <iomanip>
 #include <iostream>
 #include <string>

 int main()
 {
     std::string str;

     // reserve sufficient storage space to avoid memory reallocation
     str.reserve(50);

     std::cout << std::quoted(str) << '\\n'; // empty string

     str += "This";
     std::cout << std::quoted(str) << '\\n';

     str += std::string(" is ");
     std::cout << std::quoted(str) << '\\n';

     str += 'a';
     std::cout << std::quoted(str) << '\\n';

     str += {' ', 's', 't', 'r', 'i', 'n', 'g', '.'};
     std::cout << std::quoted(str) << '\\n';

     str += 69.96; // Equivalent to str += static_cast<char>(69.96);
                   // 'E' (ASCII code 69) is appended by overload (2),
                   // which might not be the intent.

     // To add a numeric value, consider std::to_string():
     str += std::to_string(1729);

     std::cout << std::quoted(str) << '\\n';
 }

.SH Output:

 ""
 "This"
 "This is "
 "This is a"
 "This is a string."
 "This is a string.E1729"

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to       Behavior as published              Correct behavior
   LWG 847  C++98      there was no exception safety      added strong exception safety
                       guarantee                          guarantee
   LWG 2946 C++17      overload \fB(5)\fP caused ambiguity in   avoided by making it a
                       some cases                         template

.SH See also

   append appends characters to the end
          \fI(public member function)\fP
